home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 August: Technology Seed / August 1998 ADC Seed CD.toast / Mac OS 8.5b2 / allegro-b2-pseudo-SDK / PInterfaces / UnicodeUtilities.p < prev   
Encoding:
Text File  |  1998-07-17  |  13.0 KB  |  301 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        UnicodeUtilities.p
  3.  
  4.      Contains:    Types, constants, prototypes for Unicode Utilities (Unicode input and text utils)
  5.  
  6.      Version:    Technology:    Allegro
  7.                  Release:    Allego Seed, Use with 3.1 Universal Interfaces
  8.  
  9.      Copyright:    © 1997-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT UnicodeUtilities;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __UNICODEUTILITIES__}
  28. {$SETC __UNICODEUTILITIES__ := 1}
  29.  
  30. {$I+}
  31. {$SETC UnicodeUtilitiesIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __MACTYPES__}
  35. {$I MacTypes.p}
  36. {$ENDC}
  37.  
  38.  
  39. {$PUSH}
  40. {$ALIGN MAC68K}
  41. {$LibExport+}
  42.  
  43. {
  44.    -------------------------------------------------------------------------------------------------
  45.    CONSTANTS & DATA STRUCTURES
  46.    -------------------------------------------------------------------------------------------------
  47. }
  48. {
  49.    -------------------------------------------------------------------------------------------------
  50.    UCKeyOutput & related stuff
  51.    The interpretation of UCKeyOutput depends on bits 15-14.
  52.    If they are 01, then bits 0-13 are an index in UCKeyStateRecordsIndex (resource-wide list).
  53.    If they are 10, then bits 0-13 are an index in UCKeySequenceDataIndex (resource-wide list),
  54.      or if UCKeySequenceDataIndex is not present or the index is beyond the end of the list,
  55.      then bits 0-15 are a single Unicode character.
  56.    Otherwise, bits 0-15 are a single Unicode character; a value of 0xFFFE-0xFFFF means no character
  57.      output.
  58.    UCKeyCharSeq is similar, but does not support indices in UCKeyStateRecordsIndex. For bits 15-14:
  59.    If they are 10, then bits 0-13 are an index in UCKeySequenceDataIndex (resource-wide list),
  60.      or if UCKeySequenceDataIndex is not present or the index is beyond the end of the list,
  61.      then bits 0-15 are a single Unicode character.
  62.    Otherwise, bits 0-15 are a single Unicode character; a value of 0xFFFE-0xFFFF means no character
  63.      output.
  64.    -------------------------------------------------------------------------------------------------
  65. }
  66.  
  67.  
  68. TYPE
  69.     UCKeyOutput                            = UInt16;
  70.     UCKeyCharSeq                        = UInt16;
  71.  
  72. CONST
  73.     kUCKeyOutputStateIndexMask    = $4000;
  74.     kUCKeyOutputSequenceIndexMask = $8000;
  75.     kUCKeyOutputTestForIndexMask = $C000;                        {  test bits 14-15 }
  76.     kUCKeyOutputGetIndexMask    = $3FFF;                        {  get bits 0-13 }
  77.  
  78. {
  79.    -------------------------------------------------------------------------------------------------
  80.    UCKeyStateRecord & related stuff
  81.    The UCKeyStateRecord information is used as follows. If the current state is zero,
  82.    output stateZeroCharData and set the state to stateZeroNextState. If the current state
  83.    is non-zero and there is an entry for it in stateEntryData, then output the corresponding
  84.    charData and set the state to nextState. Otherwise, output the state terminator from
  85.    UCKeyStateTerminators for the current state (or nothing if there is no UCKeyStateTerminators
  86.    table or it has no entry for the current state), then output stateZeroCharData and set the
  87.    state to stateZeroNextState.
  88.    -------------------------------------------------------------------------------------------------
  89. }
  90.  
  91.  
  92. TYPE
  93.     UCKeyStateRecordPtr = ^UCKeyStateRecord;
  94.     UCKeyStateRecord = RECORD
  95.         stateZeroCharData:        UCKeyCharSeq;
  96.         stateZeroNextState:        UInt16;
  97.         stateEntryCount:        UInt16;
  98.         stateEntryFormat:        UInt16;
  99.                                                                         {  This is followed by an array of stateEntryCount elements }
  100.                                                                         {  in the specified format. Here we just show a dummy array. }
  101.         stateEntryData:            ARRAY [0..0] OF UInt32;
  102.     END;
  103.  
  104. {
  105.    Here are the codes for entry formats currently defined.
  106.    Each entry maps from curState to charData and nextState.
  107. }
  108.  
  109. CONST
  110.     kUCKeyStateEntryTerminalFormat = $0001;
  111.     kUCKeyStateEntryRangeFormat    = $0002;
  112.  
  113. {
  114.    For UCKeyStateEntryTerminal -
  115.    nextState is always 0, so we don't have a field for it
  116. }
  117.  
  118.  
  119. TYPE
  120.     UCKeyStateEntryTerminalPtr = ^UCKeyStateEntryTerminal;
  121.     UCKeyStateEntryTerminal = RECORD
  122.         curState:                UInt16;
  123.         charData:                UCKeyCharSeq;
  124.     END;
  125.  
  126. {
  127.    For UCKeyStateEntryRange -
  128.    If curState >= curStateStart and curState <= curStateStart+curStateRange,
  129.    then it matches the entry, and we transform charData and nextState as follows:
  130.    If charData < 0xFFFE, then charData += (curState-curStateStart)*deltaMultiplier
  131.    If nextState != 0, then nextState += (curState-curStateStart)*deltaMultiplier
  132. }
  133.     UCKeyStateEntryRangePtr = ^UCKeyStateEntryRange;
  134.     UCKeyStateEntryRange = RECORD
  135.         curStateStart:            UInt16;
  136.         curStateRange:            SInt8;
  137.         deltaMultiplier:        SInt8;
  138.         charData:                UCKeyCharSeq;
  139.         nextState:                UInt16;
  140.     END;
  141.  
  142. {
  143.    -------------------------------------------------------------------------------------------------
  144.    UCKeyboardLayout & related stuff
  145.    The UCKeyboardLayout struct given here is only for the resource header. It specifies
  146.    offsets to the various subtables which each have their own structs, given below.
  147.    The keyboardTypeHeadList array selects table offsets that depend on keyboardType. The
  148.    first entry in keyboardTypeHeadList is the default entry, which will be used if the
  149.    keyboardType passed to UCKeyTranslate does not match any other entry - i.e. does not fall
  150.    within the range keyboardTypeFirst..keyboardTypeLast for some entry. The first entry
  151.    should have keyboardTypeFirst = keyboardTypeLast = 0.
  152.    -------------------------------------------------------------------------------------------------
  153. }
  154.     UCKeyboardTypeHeaderPtr = ^UCKeyboardTypeHeader;
  155.     UCKeyboardTypeHeader = RECORD
  156.         keyboardTypeFirst:        UInt32;                                    {  first keyboardType in this entry }
  157.         keyboardTypeLast:        UInt32;                                    {  last keyboardType in this entry }
  158.         keyModifiersToTableNumOffset: ByteOffset;                        {  required }
  159.         keyToCharTableIndexOffset: ByteOffset;                            {  required }
  160.         keyStateRecordsIndexOffset: ByteOffset;                            {  0 => no table }
  161.         keyStateTerminatorsOffset: ByteOffset;                            {  0 => no table }
  162.         keySequenceDataIndexOffset: ByteOffset;                            {  0 => no table }
  163.     END;
  164.  
  165.     UCKeyboardLayoutPtr = ^UCKeyboardLayout;
  166.     UCKeyboardLayout = RECORD
  167.                                                                         {  header only; other tables accessed via offsets }
  168.         keyLayoutHeaderFormat:    UInt16;                                    {  =kUCKeyLayoutHeaderFormat }
  169.         keyLayoutDataVersion:    UInt16;                                    {  0x0100 = 1.0, 0x0110 = 1.1, etc. }
  170.         keyLayoutFeatureInfoOffset: ByteOffset;                            {  may be 0                                     }
  171.         keyboardTypeCount:        ItemCount;                                {  Dimension for keyboardTypeHeadList[]         }
  172.         keyboardTypeList:        ARRAY [0..0] OF UCKeyboardTypeHeader;
  173.     END;
  174.  
  175. {  ------------------------------------------------------------------------------------------------- }
  176.     UCKeyLayoutFeatureInfoPtr = ^UCKeyLayoutFeatureInfo;
  177.     UCKeyLayoutFeatureInfo = RECORD
  178.         keyLayoutFeatureInfoFormat: UInt16;                                {  =kUCKeyLayoutFeatureInfoFormat }
  179.         reserved:                UInt16;
  180.         maxOutputStringLength:    UniCharCount;                            {  longest possible output string }
  181.     END;
  182.  
  183. {  ------------------------------------------------------------------------------------------------- }
  184.     UCKeyModifiersToTableNumPtr = ^UCKeyModifiersToTableNum;
  185.     UCKeyModifiersToTableNum = RECORD
  186.         keyModifiersToTableNumFormat: UInt16;                            {  =kUCKeyModifiersToTableNumFormat }
  187.         defaultTableNum:        UInt16;                                    {  For modifier combos not in tableNum[] }
  188.         modifiersCount:            ItemCount;                                {  Dimension for tableNum[] }
  189.         tableNum:                SInt8;
  190.                                                                         {  Then there is padding to a 4-byte boundary with bytes containing 0, if necessary. }
  191.     END;
  192.  
  193. {  ------------------------------------------------------------------------------------------------- }
  194.     UCKeyToCharTableIndexPtr = ^UCKeyToCharTableIndex;
  195.     UCKeyToCharTableIndex = RECORD
  196.         keyToCharTableIndexFormat: UInt16;                                {  =kUCKeyToCharTableIndexFormat }
  197.         keyToCharTableSize:        UInt16;                                    {  Max keyCode (128 for ADB keyboards) }
  198.         keyToCharTableCount:    ItemCount;                                {  Dimension for keyToCharTableOffsets[] (usually 6 to 12 tables) }
  199.         keyToCharTableOffsets:    ARRAY [0..0] OF ByteOffset;
  200.                                                                         {  Each offset in keyToCharTableOffsets is from the beginning of the resource to a }
  201.                                                                         {  table as follows: }
  202.                                                                         {     UCKeyOutput        keyToCharData[keyToCharTableSize]; }
  203.                                                                         {  These tables follow the UCKeyToCharTableIndex. }
  204.                                                                         {  Then there is padding to a 4-byte boundary with bytes containing 0, if necessary. }
  205.     END;
  206.  
  207. {  ------------------------------------------------------------------------------------------------- }
  208.     UCKeyStateRecordsIndexPtr = ^UCKeyStateRecordsIndex;
  209.     UCKeyStateRecordsIndex = RECORD
  210.         keyStateRecordsIndexFormat: UInt16;                                {  =kUCKeyStateRecordsIndexFormat }
  211.         keyStateRecordCount:    UInt16;                                    {  Dimension for keyStateRecordOffsets[] }
  212.         keyStateRecordOffsets:    ARRAY [0..0] OF ByteOffset;
  213.                                                                         {  Each offset in keyStateRecordOffsets is from the beginning of the resource to a }
  214.                                                                         {  UCKeyStateRecord. These UCKeyStateRecords follow the UCKeyToCharTableIndex. }
  215.                                                                         {  Then there is padding to a 4-byte boundary with bytes containing 0, if necessary. }
  216.     END;
  217.  
  218. {  ------------------------------------------------------------------------------------------------- }
  219.     UCKeyStateTerminatorsPtr = ^UCKeyStateTerminators;
  220.     UCKeyStateTerminators = RECORD
  221.         keyStateTerminatorsFormat: UInt16;                                {  =kUCKeyStateTerminatorsFormat }
  222.         keyStateTerminatorCount: UInt16;                                {  Dimension for keyStateTerminators[] (# of nonzero states) }
  223.         keyStateTerminators:    ARRAY [0..0] OF UCKeyCharSeq;
  224.                                                                         {  Note: keyStateTerminators[0] is terminator for state 1, etc. }
  225.                                                                         {  Then there is padding to a 4-byte boundary with bytes containing 0, if necessary. }
  226.     END;
  227.  
  228. {  ------------------------------------------------------------------------------------------------- }
  229.     UCKeySequenceDataIndexPtr = ^UCKeySequenceDataIndex;
  230.     UCKeySequenceDataIndex = RECORD
  231.         keySequenceDataIndexFormat: UInt16;                                {  =kUCKeySequenceDataIndexFormat }
  232.         charSequenceCount:        UInt16;                                    {  Dimension of charSequenceOffsets[] is charSequenceCount+1 }
  233.         charSequenceOffsets:    ARRAY [0..0] OF UInt16;
  234.                                                                         {  Each offset in charSequenceOffsets is in bytes, from the beginning of }
  235.                                                                         {  UCKeySequenceDataIndex to a sequence of UniChars; the next offset indicates the }
  236.                                                                         {  end of the sequence. The UniChar sequences follow the UCKeySequenceDataIndex. }
  237.                                                                         {  Then there is padding to a 4-byte boundary with bytes containing 0, if necessary. }
  238.     END;
  239.  
  240. {  ------------------------------------------------------------------------------------------------- }
  241. {  Current format codes for the various tables (bits 12-15 indicate which table) }
  242.  
  243.  
  244. CONST
  245.     kUCKeyLayoutHeaderFormat    = $1002;
  246.     kUCKeyLayoutFeatureInfoFormat = $2001;
  247.     kUCKeyModifiersToTableNumFormat = $3001;
  248.     kUCKeyToCharTableIndexFormat = $4001;
  249.     kUCKeyStateRecordsIndexFormat = $5001;
  250.     kUCKeyStateTerminatorsFormat = $6001;
  251.     kUCKeySequenceDataIndexFormat = $7001;
  252.  
  253. {
  254.    -------------------------------------------------------------------------------------------------
  255.    Error codes - these will eventually move to Errors.[ahp]
  256.    The error code range for Unicode Utilities is -25340 to -25379.
  257.    -------------------------------------------------------------------------------------------------
  258. }
  259.  
  260.     kUCOutputBufferTooSmall        = -25340;                        {  Output buffer too small for Unicode string result }
  261.  
  262. {
  263.    -------------------------------------------------------------------------------------------------
  264.    Constants for keyAction parameter in UCKeyTranslate() 
  265.    -------------------------------------------------------------------------------------------------
  266. }
  267.  
  268.     kUCKeyActionDown            = 0;                            {  key is going down }
  269.     kUCKeyActionUp                = 1;                            {  key is going up }
  270.     kUCKeyActionAutoKey            = 2;                            {  auto-key down }
  271.     kUCKeyActionDisplay            = 3;                            {  get information for key display (as in Key Caps)             }
  272.  
  273. {
  274.    -------------------------------------------------------------------------------------------------
  275.    Bit assignments & masks for keyTranslateOptions parameter in UCKeyTranslate() 
  276.    -------------------------------------------------------------------------------------------------
  277. }
  278.  
  279.     kUCKeyTranslateNoDeadKeysBit = 0;                            {  Prevents setting any new dead-key states }
  280.  
  281.     kUCKeyTranslateNoDeadKeysMask = $00000001;
  282.  
  283. {
  284.    -------------------------------------------------------------------------------------------------
  285.    FUNCTION PROTOTYPES
  286.    -------------------------------------------------------------------------------------------------
  287. }
  288.  
  289. FUNCTION UCKeyTranslate(VAR keyLayoutPtr: UCKeyboardLayout; virtualKeyCode: UInt16; keyAction: UInt16; modifierKeyState: UInt32; keyboardType: UInt32; keyTranslateOptions: OptionBits; VAR deadKeyState: UInt32; maxStringLength: UniCharCount; VAR actualStringLength: UniCharCount; VAR unicodeString: UniChar): OSStatus;
  290.  
  291. {$ALIGN RESET}
  292. {$POP}
  293.  
  294. {$SETC UsingIncludes := UnicodeUtilitiesIncludes}
  295.  
  296. {$ENDC} {__UNICODEUTILITIES__}
  297.  
  298. {$IFC NOT UsingIncludes}
  299.  END.
  300. {$ENDC}
  301.